========= EUTIL.EXE ========= EUTIL is a database maintenance utility for EllTech Development's "E- Tree Plus" library. It provides the following functions: * Set or view the values of EtAuto fields. * "Clone" the file structure and index definitions of an existing E- Tree plus database file to a new, empty file. * "Create" a new E-Tree file using a special "description file." * Generate a "Description" file for an existing E-Tree file. * "Drop" (delete) an existing index. * "Export" data from an E-Tree file to a comma-delimited ASCII file. * "Import" data from a comma-delimited file into an existing E-Tree file. * Create a new "Index." * "Rebuild" or pack an existing E-Tree file. * "Reset" the database header and record lock semaphores. * Get the "Status" of an existing E-Tree file. This includes a summary of the field names, index definitions, and other related information. USING EUTIL =========== EUTIL is a command-line driven utility that may be freely distributed with the applications you develop using E-Tree Plus. It's syntax is as follows: EUTIL -Switch EtreeFile [other options] The first command line argument is always a "switch" that indicates the desired EUTIL operation. EtreeFile is the name of the E-Tree database file that will be created or manipulated. The other options vary depending on the switch used. If EUTIL is executed without an command line arguments, a summary of available switches and options will be displayed. During potentially long operations (rebuild, import, export), you can press the Escape key to terminate the current operation. You'll be asked to confirm this choice before EUTIL actually terminates. If EUTIL terminates are a result of an error, the DOS "errorlevel" will be set to a value of one. If termination resulted from the user pressing Escape, the errorlevel will be set to a value of two. EUTIL's output may be redirected to a DOS file or device by using the ">" redirection symbol on the DOS command line: EUTIL [switches and options] > FileOrDevice Redirection is automatically detected within EUTIL and, during such operation, prompts for user input are bypassed. EUTIL SERVICES ============== The following is a list of EUTIL's command line switches and a description of their use. Only the first three characters of each switch is significant. That is, "-Clone" can be abbreviated "-Clo", etc. -AUTOINCREMENT EtreeFile [FldName [NextValue]] This switch is used to view the current auto increment value of a specied field (or all EtAuto field), or to set a specific EtAuto field to a specific value. For example: EUTIL -AUT TEST.ETR Displays the current values of all EtAuto fields. EUTIL -AUT TEST.ETR FldName Displays the current value of the field named "FldName". EUTIL -AUT TEST.ETR FldName 1234 Sets auto increment value for FldName to 1234. The next new record inserted into the database will have 1234 assigned to the FldName field (assuming that field had a value of zero when inserted). -CLONE ETreeFile NewFile This service "clones" or copies an existing E-Tree database file's (ETreeFile) structure to a new, empty file (NewFile). The structure copied includes field and index definitions only. No record data is copied. For example: EUTIL -CLO TEST.ETR NEWFILE.ETR This command creates an empty database file called "NEWFILE.ETR" which has the same structure as TEST.ETR. -CREATE EtreeFile DescFile This service reads a "database description file" (DescFile) and creates an E-Tree database file based on that description. The description file includes the names, types and lengths of fields, and index names. It can optionally define the file page size, maximum number of indices the file will contain (MaxKeys), and the amount of disk space that will be pre-allocated to the file. The following is a sample description file: ' This is an EUTIL database description file. It is structured as ' follows: ' ' Lines beginning with an apostrophe are ignored (good for comments) ' "#Fields" is a metacommand which must preceed field names. ' Field name entries are structured as follows: ' ' FieldName FieldType FieldLength ' ' Field lengths are needed only for String fields. See page page 33 of ' the E-Tree documentation under "Named Constants" for a list of valid ' field types. If wish to include a variable-length field, it must be ' the -last- field defined. ' ' #Index is a metacommand that must preceed index definitions. #Fields ' MUST preceed #Index. #Index entries must be structured as follows: ' ' IndexName [Unique] [FieldName [FieldName ... etc.]] ' ' IF "Unique" is omitted, duplicate key values will be allow for the ' index. If FieldName is omitted, it is assumed that the key will have ' a single segment which is comprised of the field with the same name ' as the Index. ' ' #PageSize allows you to define the file page size: #PageSize 8192. ' Using a value of 0 (or omitting #PageSize altogether) will direct ' EUTIL to calculate a page size optimized for performance (yielding ' larger files). Using a value of -1 directs EUTIL to calculate a page ' size optimized for file size (smaller files with slightly slower ' performance). ' ' #MaxKeys allows you to define the maximum number of indices you'll be ' using at once. If #PageSize > 0 then the #MaxKeys value is ignored. ' ' #PreAllocation allows you to "pre-allocate" the specified amount of ' disk space (in bytes) to the file. ' ' EUTIL can build a description file for an existing E-Tree database ' file. See the documentation for the -DEF. ' The following will create an E-Tree file matching the one in ' EXAMPLE.BAS. #PageSize -1 'Comments can also be placed out here #MaxKeys 5 ' just like in your BASIC program. #Fields CustNumber EtAuto 1234 'The "1234" is the optional starting value FirstName EtString 20 LastName EtString 20 Addr EtString 30 City EtString 20 State EtString 2 ZipCode EtString 10 AreaCode EtString 3 PhoneNum EtString 8 AmountDue EtDouble Age EtInteger #Index CustNumber Unique FullName LastName FirstName ZipCode AmountDue '-----------------------End of Description file----------------------- -DESCRIPTION ETreeFile [DescFile] This service creates a description file (DescFile) for an existing E- Tree Plus database file (ETreeFile). The output description file name is optional. If omitted, the name ETreeFile.DES will be used. -DROP ETreeFile IndexName This service "drops" or "deletes" an index (IndexName) from an E-Tree database file (ETreeFile). -EXPORT ETreeFile OutputFile [FldDescFile] This service exports all data from ETreeFile to OutputFile in standard comma-delimited ASCII format, one record per line in the OutputFile. FldDescFile is a standard ASCII text file which contains a list of the fields that you want to export. This FldDescFile should contain only one line consisting of a list of field names with each seperated by a comma. For example: LastName,FirstName,CustNumber,ZipCode Using the above FldDescFile, the OutputFile will contain only the above list of fields. If FldDescFile is omitted, all fields comprising each record will be exported. Also, the first line of OutputFile will contain the list of field names exported in the same order which the data appears in the file. This information can be used by the -IMPORT function to determine the order of the data in OutputFile and the fields into which the data should be placed. -HEADER EtreeFile ["New Database ID String"] Assigns a new database ID to ETreeFile. If the database ID is omitted, the default ID of "EllTech Development Corp. E-Tree ISAM Version 1.0" will be assigned. If you change the database ID from the default, you must call the EtSetID routine in your program before you can open the database with EtOpen. Failure to do so will result in a Status of -9. -IMPORT ETreeFile InputFile [FldDescFile] This service imports data from a comma-delimited ASCII file (InputFile) into an E-Tree database file (ETreeFile). FldDescFile is an ASCII text file structure as described in the -EXPORT service (above). It simply lists the names of the ETreeFile's fields into which the data will be inserted. If FldDescFile is omitted, the first line of InputFile must contain the field name information (in the same format as FldDescFile). -INDEX ETreeFile IndexName [Unique] [FldName [FldName...]] This service creates an index (IndexName) in the specified E-Tree database file (ETreeFile). The "Unique" keyword can follow the IndexName to instruct EUTIL that duplicate key values for IndexName are NOT allowed. One or more FldNames can also be listed to instruct EUTIL of the various segments comprising the index. If no FldNames are listed, it is assumed that a field with the same name as IndexName will be the only segment for this index. -REBUILD ETreeFile This service is used to "pack" or recover a corrupted E-Tree database file. Because of the very efficient method E-Tree uses to track and reuse "dead" space within a database file, packing is rarely necessary. However, if your E-Tree file is corrupt, this service will recover most (if not all) of the record data and indices stored in the file. EUTIL displays an error message pertaining to any data that could not be recovered. The output file is called ETreeFile.REB. -RESET ETreeFile This service resets the file header and record locking "semaphores" within ETreeFile. Use of this service should only be necessary if a program or network workstation "crashes" with record locks in place, thus preventing E-Tree's record manager from properly releasing those locks automatically. This service should only be used when no other processes are accessing the database file. -STATUS ETreeFile This service displays a summary of ETreeFile's record and index structure, as well as other information containing in the file's header (number of active records, etc.).